Hi @aaronpowell,

Thank you so much for looking into this.

#797 is an instructions file that works in the background when an agent needs to create new Markdown content, as well as during code reviews on GitHub.com. It has already proven to be helpful in my work.

I initially thought of creating a skill, but in all the documentation I reviewed, I could not confirm whether skills participate in code reviews on GitHub.com. If the code review agent can use skills, that would definitely be a reason to turn it into a skill, because it could also be invoked to review a specific file.

If we turn #768 into a skill, we would lose the turn-by-turn conversation with a persistent identity, as well as the teaching aspect I had in mind for it.

Right now, #797 works in the background to guide agents when generating new Markdown content and during code reviews. #768, on the other hand, can do more in-depth reviews of specific files and answer questions about Markdown accessibility. Another difference is that the agent in #768 uses a linter and a more detailed workflow for more thorough reviews.

I see them as playing different roles, but I also understand there is significant overlap between the two. If you believe a skill combining the two would accomplish the same goals, I am happy to make the change.

I initially thought of creating a skill, but in all the documentation I reviewed, I could not confirm whether skills participate in code reviews on GitHub.com. If the code review agent can use skills, that would definitely be a reason to turn it into a skill, because it could also be invoked to review a specific file.

That's a really good point in where an instructions file is going to provide value over the top of a skill, but let me follow up with the Copilot Code Review team to see if maybe it's not a missing bit of docs.

The reason why I ask the question in general is that I'm wanting to reduce the number of overlapping items we have in this repo as it can cause confusion as to when you should use A over B.

You mention that the turn-by-turn conversation with an agent was part of what led you to create it as an agent in the first place, but I challenge you on whether that wouldn't be available still if it was a skill? I feel like you would actually see it leveraged more as a skill since the agent could choose to use the skill during its run rather than having to have you initially started the conversation from a custom agent. I'm thinking of the workflow of where you've done a refactor of part of an application and now you need to update the relevant docs, and you enter the prompt "now update the docs/feature.md based off the work". A skill can be picked up in that and applied, whereas if it's a custom agent you have to have opted into it prior to sending that prompt, and if it's in an existing conversation, it can be easy to forget that you need to switch agents.

I think you are right. If I turn it into a skill, however, I may need to reconsider how it uses the linter, because we would not want a linter to be invoked each time markdown content is generated. Maybe adding a note to only use the linter to review entire documents when appropriate, and let the model decide. I can test and refine over time.

I will wait until you hear back from the code review team. Thank you very much for your help with this.